feat: authorization-zone intents for third-party keepers (#370) - #373

Summary

• Implemented an on-chain authorization-zone intent and keeper framework allowing third parties to execute scoped operational actions on behalf of users/protocol without transferring asset custody or granting unbounded permissions.
• Added 3 core keeper action flows:
  1. execute_keeper_resolve: permissioned oracle payload resolution under an active KeeperScope::Resolve intent.
  2. execute_keeper_claim: user winning claims executed by an authorized keeper under a KeeperScope::Claim intent, guaranteeing that all claimed winnings are credited directly to the user's custody (accumulate_pending).
  3. execute_keeper_create_next: automated template-based round rollover executed under a KeeperScope::CreateNext intent.
• Added strict capability security controls:
  • Scoped authority (KeeperScope) preventing privilege escalation across action domains.
  • Per-user/scope sequential nonces preventing intent replay attacks.
  • Expiry ledger enforcement (expires_at_ledger) with validation (MIN_INTENT_EXPIRY_LEDGERS = 6, MAX_INTENT_EXPIRY_LEDGERS = 172,800).
  • User revocation mechanism (revoke_keeper_intent).
  • Optional admin-controlled keeper registration gate (register_keeper, deregister_keeper, set_keeper_registration_required).
• Documented security analysis in docs/INTENT_THREAT_MODEL.md.
• Exported TypeScript client bindings and error classes in bindings/src/helpers.ts.

Why

Third-party automation services (keepers, bots, relayer networks) need the ability to perform operational tasks (settling expired rounds, claiming user rewards, rolling over rounds) without:

1. Gaining custody over user funds or tokens.
2. Holding permanent or unscoped execution authority.
3. Being vulnerable to signature replay across different contract rounds or ledgers.

This capability-security authorization framework enforces strict scoped permissions, replay resistance, expiry windows, and revocation safety.

Implementation

1. Core Intent Module (contracts/src/intents.rs):

   • authorize_keeper_intent(env, user, keeper, scope, duration_ledgers) -> u64: Authorizes a keeper with a monotonic per-scope nonce and expiry ledger.
   • revoke_keeper_intent(env, user, scope, nonce) -> Result<(), ContractError>: Explicit user revocation.
   • get_keeper_intent(env, user, scope, nonce) -> Option<KeeperIntent>: Observability query.
   • execute_keeper_resolve(env, keeper, user, nonce, payload) -> Result<(), ContractError>: Gated resolution.
   • execute_keeper_claim(env, keeper, user, nonce) -> Result<i128, ContractError>: Gated claim preserving user custody.
   • execute_keeper_create_next(env, keeper, user, nonce) -> Result<u64, ContractError>: Gated round rollover.
   • register_keeper, deregister_keeper, set_keeper_registration_required, is_keeper_registered, is_keeper_registration_required: Optional keeper allowlist gating.

2. Types & Storage (contracts/src/types.rs, contracts/src/errors.rs):

   • Added KeeperScope (Resolve, Claim, CreateNext), KeeperIntentStatus (Active, Consumed, Revoked), KeeperIntent, IntentKey.
   • Added ContractError codes 80–87 for intent error handling.
   • Implemented manual conversion traits for ContractError to handle the SDK error conversion and variant limits safely.

3. Contract Interface (contracts/src/contract.rs, contracts/src/lib.rs):

   • Exposed all 11 intent/keeper entrypoints on VirtualTokenContract.

4. Test Suite (contracts/src/tests/intents.rs):

   • 10 automated unit test cases covering happy path claim, create-next, authorization, expiry enforcement, replay rejection, scope isolation, revocation, and keeper registration gates.

Testing

Executed automated test suite:

• cargo check --lib (clean build)
• cargo test --lib -- tests::intents

running 10 tests
test tests::intents::test_invalid_expiry_rejected ... ok
test tests::intents::test_authorize_and_get_intent ... ok
test tests::intents::test_keeper_mismatch_rejected ... ok
test tests::intents::test_expired_intent_rejected ... ok
test tests::intents::test_keeper_create_next_happy_path ... ok
test tests::intents::test_revoked_intent_rejected ... ok
test tests::intents::test_keeper_registration_requirement ... ok
test tests::intents::test_scope_cannot_escalate ... ok
test tests::intents::test_replayed_intent_rejected ... ok
test tests::intents::test_keeper_claim_happy_path_and_custody_preservation ... ok

test result: ok. 10 passed; 0 failed; 0 ignored; 0 measured; finished in 0.92s
Scope / Risk
Affected areas: contracts/src/intents.rs, contracts/src/contract.rs, contracts/src/types.rs, contracts/src/errors.rs, docs/INTENT_THREAT_MODEL.md, bindings/src/helpers.ts.
Breaking changes: None. Existing direct resolution, direct claim, and manual round creation remain fully backward-compatible and open.
Issue
closes #370